<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!--
 ~ Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
 ~
 ~ WSO2 Inc. licenses this file to you under the Apache License,
 ~ Version 2.0 (the "License"); you may not use this file except
 ~ in compliance with the License.
 ~ You may obtain a copy of the License at
 ~
 ~    http://www.apache.org/licenses/LICENSE-2.0
 ~
 ~ Unless required by applicable law or agreed to in writing,
 ~ software distributed under the License is distributed on an
 ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~ KIND, either express or implied.  See the License for the
 ~ specific language governing permissions and limitations
 ~ under the License.
 -->
<html>
<head>
    <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"/>
    <title>Rest API - User Guide</title>
    <link href="../../admin/css/documentation.css" rel="stylesheet" type="text/css" media="all"/>
</head>

<body>
<h1>REST API Management</h1>

Use the <span style="font-style: italic; font-weight: bold;">API
Management</span> page to add new APIs or edit/delete existing APIs. 

As shown in Figure,1 the Deployed APIs page displays the names of the
existing APIs. The Edit action will take direct the user to the Edit API page
whereas the Delete action will confirm and remove the API from the
configuration. The Add API action will direct the user to the Add API page.
<br/>

<div class="image">
<img src="images/show_apis.png" alt=""/>
<p>Figure 1: Show Existing APIs</p>
</div>
<br/>

<h3>Adding an API</h3>
Click on the <b>Add API</b> link. The <span style="font-weight: bold; font-style: italic;">
Add API</span> page will be displayed as shown below.
<br/>

<div class="image">
<img src="images/add_api.png" alt=""/>
<p>Figure 2: Add API</p>
</div>

An API requires a Name, Context and at least one Resource. The Context should always contain
a proceeding '/' character. In the design view, this character has been added by default
and therefore will not require the user to re-enter. (See the / character before the text
box of the Context).Hostname can be utilized to filter (incoming message 'hostname' details are included in the message transport headers)
the given REST API resource with the incoming requests from client.
<br/><br/>
Click on the <b>Add Resource</b> link to add a Resource to the API. A form for entering Resource information
will be displayed below the API management section. See Figure 3.
<br/><br/>

<div class="image">
<img src="images/resource_info.png" alt=""/>
<p>Figure 3: Resource Information</p>
</div>
<br/>

<ul>
   <li>Rules for Resources
	<ul>
	<li>
	   A Resource should contain at least one method. Specifying the Resource methods are done by checking
           on the relevant check boxes.	
	</li>
	<li>
	   An API can have at most one default Resource (a Resource with neither a uri-template
           nor url-mapping).	
	</li>
	<li>
	   A Resource may have an In-Sequence, Out-Sequence and a Fault-Sequence,configuration can be defined using either
	   in-line,or selecting configuration from the registry or can use existing sequence defined at the local registry.
	</li>
	</ul>      	
   </li>
</ul>

<br/>
Click on the <b>Update</b> button to update the Resource. The Resource information section will be removed and a child
Resource element will be added to the API tree. See Figure 4. 
<br/>
Clicking on the Resource icon on the tree will load
the Resource Information section back again with details of the particular Resource.
<br/><br/>

<div class="image">
<img src="images/api_tree.png" alt=""/>
<p>Figure 4: API Tree</p>
</div>
<br/>

Once all API and Resource information has been entered, clicking on the <b>Save button</b> will cause the API to be saved
in the ESB configuration. A confirmation message will also be shown as below.
<br/><br/>

<div class="image">
<img src="images/add_success.png" alt=""/>
<p>Figure 5: Add API Success</p>
</div>
<br/>

<h3>Editing an API</h3>

Editing a saved API can be done by clicking on the Edit link on the Deployed APIs page. This will redirect the user
to a page on which the API information will be loaded. When in the Edit mode, changing the API name will not be allowed.
<br/>
Adding new Resources, Editing/Deleting existing Resources are allowed.
<br/>
Once the modification of the API information is complete, clicking on the <b>Save</b> button will result in the API details being
saved in the ESB configuration. A confirmation message will also be shown as below.
<br/><br/>

<div class="image">
<img src="images/edit_success.png" alt=""/>
<p>Figure 6: Edit API Success</p>
</div>
<br/>

<h3>Source View</h3>

Clicking on the <b>Switch to source view</b> link will result in the xml source of the API to be displayed. The Source
View and Design View are synchronized. Changes made to the Design View are reflected on the Source View and vice
versa. See image below.
<br/><br/>

<div class="image">
<img src="images/source_view.png" alt=""/>
<p>Figure 7: Source View</p>
</div>
<br/>

<p>For <a href="http://wso2.org/library/esb">more information</a> please refer to the WSO2 library</p>
</body>
</html>
